/*
 * Created on 15.09.2005
 */
package org.eclipse.core.runtime;

public interface IStatus {
    /** Status severity constant (value 0) indicating this status represents the nominal case.
     * This constant is also used as the status code representing the nominal case.
     * @see #getSeverity()
     * @see #isOK()
     */
    public static final int OK = 0;

    /** Status type severity (bit mask, value 1) indicating this status is informational only.
     * @see #getSeverity()
     * @see #matches(int)
     */
    public static final int INFO = 0x01;

    /** Status type severity (bit mask, value 2) indicating this status represents a warning.
     * @see #getSeverity()
     * @see #matches(int)
     */
    public static final int WARNING = 0x02;

    /** Status type severity (bit mask, value 4) indicating this status represents an error.
     * @see #getSeverity()
     * @see #matches(int)
     */
    public static final int ERROR = 0x04;

    /** Status type severity (bit mask, value 8) indicating this status represents a
     * cancelation
     * @see #getSeverity()
     * @see #matches(int)
     * @since 3.0
     */
    public static final int CANCEL = 0x08;

    /**
     * Returns a list of status object immediately contained in this
     * multi-status, or an empty list if this is not a multi-status.
     *
     * @return an array of status objects
     * @see #isMultiStatus()
     */
    public IStatus[] getChildren();

    /**
     * Returns the plug-in-specific status code describing the outcome.
     *
     * @return plug-in-specific status code
     */
    public int getCode();

    /**
     * Returns the relevant low-level exception, or <code>null</code> if none. 
     * For example, when an operation fails because of a network communications
     * failure, this might return the <code>java.io.IOException</code>
     * describing the exact nature of that failure.
     *
     * @return the relevant low-level exception, or <code>null</code> if none
     */
    public Throwable getException();

    /**
     * Returns the message describing the outcome.
     * The message is localized to the current locale.
     *
     * @return a localized message
     */
    public String getMessage();

    /**
     * Returns the unique identifier of the plug-in associated with this status
     * (this is the plug-in that defines the meaning of the status code).
     *
     * @return the unique identifier of the relevant plug-in
     */
    public String getPlugin();

    /**
     * Returns the severity. The severities are as follows (in
     * descending order):
     * <ul>
     * <li><code>CANCEL</code> - cancelation occurred</li>
     * <li><code>ERROR</code> - a serious error (most severe)</li>
     * <li><code>WARNING</code> - a warning (less severe)</li>
     * <li><code>INFO</code> - an informational ("fyi") message (least severe)</li>
     * <li><code>OK</code> - everything is just fine</li>
     * </ul>
     * <p>
     * The severity of a multi-status is defined to be the maximum
     * severity of any of its children, or <code>OK</code> if it has
     * no children.
     * </p>
     *
     * @return the severity: one of <code>OK</code>, <code>ERROR</code>, 
     * <code>INFO</code>, <code>WARNING</code>,  or <code>CANCEL</code>
     * @see #matches(int)
     */
    public int getSeverity();

    /**
     * Returns whether this status is a multi-status.
     * A multi-status describes the outcome of an operation
     * involving multiple operands.
     * <p>
     * The severity of a multi-status is derived from the severities
     * of its children; a multi-status with no children is
     * <code>OK</code> by definition.
     * A multi-status carries a plug-in identifier, a status code,
     * a message, and an optional exception. Clients may treat
     * multi-status objects in a multi-status unaware way.
     * </p>
     *
     * @return <code>true</code> for a multi-status, 
     *    <code>false</code> otherwise
     * @see #getChildren()
     */
    public boolean isMultiStatus();

    /**
     * Returns whether this status indicates everything is okay
     * (neither info, warning, nor error).
     *
     * @return <code>true</code> if this status has severity
     *    <code>OK</code>, and <code>false</code> otherwise
     */
    public boolean isOK();

    /**
     * Returns whether the severity of this status matches the given
     * severity mask. Note that a status with severity <code>OK</code>
     * will never match; use <code>isOK</code> instead to detect
     * a status with a severity of <code>OK</code>.
     *
     * @param severityMask a mask formed by bitwise or'ing severity mask
     *    constants (<code>ERROR</code>, <code>WARNING</code>,
     *    <code>INFO</code>, <code>CANCEL</code>)
     * @return <code>true</code> if there is at least one match, 
     *    <code>false</code> if there are no matches
     * @see #getSeverity()
     * @see #CANCEL
     * @see #ERROR
     * @see #WARNING
     * @see #INFO
     */
    public boolean matches(int severityMask);
    
}
